fix(cloudkit): surface per-record modify errors instead of discarding them - #354

Proposed change

CloudKit answers 200 for a modify whose records were rejected, and puts the reason in the
record entry. CKModifyResponse.records is already typed
list[CKRecord | CKTombstoneRecord | CKErrorItem], so the error is modelled — but nothing
looked at it.

Every caller scanned for a CKRecord with a matching name, did not find one, and reported
something of its own invention. Invites raised "modify response missing record", which reads
like a response-shape problem. Photos filters errors out with an isinstance check. Reminders
does not look at all — a caller ignoring the return value would see a silent no-op.

modify() now raises CloudKitApiError naming every rejected record with Apple's code and
reason, carrying the response as the payload.

What this recovered, immediately

InvitesService.rsvp() reported:

RSVP modify response missing record '…_rsvp'

What Apple actually said was:

CONFLICT (record to insert already exists)

An entirely different problem, and it pointed straight at the cause: rsvp() chooses between
create and update by looking for the existing response in event.rsvps, and event hydration
was silently returning none of them. That is #350, fixed in #352. With both in place the write
takes effect — verified live on an event with no guests, GOING → MAYBE with a message, and
back.

So the chain was: a rejected query, discarded → empty hydration → wrong operation type → a
rejected write, also discarded → a message about response shape. Two swallowed errors between
the cause and the symptom, and this PR removes the second.

Scope

Raising rather than collecting, because no caller could have been relying on partial-failure
semantics: none of the three services inspect record errors at all today, so none can
distinguish a partial success from a total one. If a future caller wants per-record outcomes
for a non-atomic batch, the payload carries the full response and the behaviour can be
widened then.

Type of change

• Dependency upgrade
• Bugfix (non-breaking change which fixes an issue)
• New service (thank you!)
• New feature (which adds functionality to an existing service)
• Breaking change (fix/feature causing existing functionality to break)
• Code quality improvements to existing code or addition of tests
• Documentation or code sample

Additional information

• This PR fixes or closes issue: CloudKit per-record modify errors are discarded, hiding failed writes #353
• This PR is related to issue: InvitesService.rsvps() fails for events you host: per-zone query rejected by CloudKit #350 and fix(invites): read RSVPs through zone changes, not a zone query #352, whose real cause this made visible

Cut from main, touching only pyicloud/common/cloudkit/client.py and
tests/test_cloudkit_client.py. Independent of my other open PRs, though it and #352 are more
useful together.

Testing. 936 tests pass on Python 3.10, 3.11, 3.12, 3.13 and 3.14, run locally. Three are
new: a rejected record surfaces Apple's code and reason, a batch names every rejected record,
and a successful modify is unaffected.

No existing test needed changing, which is itself worth noting: nothing in the suite asserted
the old behaviour, because the old behaviour was to say nothing.

Checklist

• The code change is tested and works locally.
• Local tests pass. Your PR cannot be merged unless tests pass
• There is no commented out code in this PR.
• Tests have been added to verify that the new code works.

If user exposed functionality or configuration variables are added/changed:

• Documentation added/updated to README

🤖 Generated with Claude Code